Om denna portal

Detta är en portal för utvecklare och IT-arkitekter som önskar använda API:er publicerade av SF Integrationsförvaltning. Här hittas publika API-specifikationer, men oftast inte själva API:et som sådant (det senare kallas här API-instans/-implementation). Syftet med denna portal är att kunna hänvisa till API-specifikationer som ej är av känslig karaktär. Andra typer av API:er publiceras internt, för åtkomst till dessa behöver du ett konto och rätt åtkomst. Kontakta SF Integrationsförvaltning genom Tellus och ange ditt syfte med att få ett konto.

Om Integrationsförvaltningen

Integrationsförvaltningen är en del av Stockholms läns landsting och är en egen förvaltning som levererar olika typer av integrationstjänster. Primär målgrupp är olika vårdgivare och vårdproducenter samt företag och organisationer som stödjer vårdprocesser på olika sätt. Integrationsförvaltningen hanterar även informationsutbyte mellan andra organisationer och verksamheter både på regional och nationell nivå.

API-specifikation och -instans

Ett API är ett programmeringsgränssnitt för applikationer, som både behöver beskrivas och implementeras. I detta konceptuella exempel, består ett API av två olika delar, en specifikation (beskriver användningen av ett API för båda människa och dator) och en eller flera instanser av det specificerade API:et.

Ett API kan ha i syfte att endast göra en specifik sak (ofta kallat mikrotjänst) eller är så stort att det hanterar all informationsutbyte för en datamängd/ett system.

Det finns flera typer av API:er och flera typer av webbtjänster, men i detta fall hanteras det som kallas för REST-tjänster inom gruppen webbtjänster.

API-specifikationen är skriven i format som både dator och människa kan förstå. Detta göras primärt i specifikationsformaten RAML (1.0) och OpenAPI Specification (OAS 3.0). Även om specifikationerna går att läsa i en vanlig texthanterare, så kan det vara svårt att tyda och förstå i vissa lägen. Därför visas specifikationer, som är uppladdade i denna portal, upp för användaren på ett mer lättförståeligt och intuitivt sätt. Portalen delar upp resurser i olika metoder och delar och gör det möjligt för användaren att direkt kunna testa API:et via så kallade "mockade endpoints". Det innebär att användaren/utvecklaren kan testa implementationer av specifikationen med hjälp av exempeldata, utan att på något sätt kan påverka den vanliga driften, utan att något system behöver finnas bakom test-ytan.

En specifikation behöver inte innehålla alla delar hos ett API, utan endast de delar som API-ägaren önskar att konsumenten får ta dela av. Detta gör det möjligt för ett bakomliggande system enbart exponera ett litet urval av informationsresurser mot omvärlden och API-instansen begränsar konsumenten till att endast verka i den önskade miljön.

En specifikation kan bestå av flera olika delar som går att återanvända mellan olika specifikationer, exempelvis återanvändbara datatyper och egenskaper för en metod. Dessa kallas ofta "API-fragment".

API-specifikationen är sammanfattningsvis inte det faktiska API:et, utan snarare en beskrivning för hur interaktionen mot API:et ska ske och beskrivningen kan läsas av både dator och människa. Vad som faktiskt händer "inne i" eller bakom "API:et" behöver inte vara dokumenterat i API-specifikation, utan är troligare en del i en större systemdokumentation för systemet som exponerar API:et.

API-instans är instansiering av ett API och denna har en unik "endpoint" (punkt där API svarar på anrop, exempelvis https://mitt-api.exempel.regionstockholm.se/api/resurs/123). Det implementerade API:et ska bete sig enligt API-specifikationenm, så att anropande system (konsumenten) har möjlighet att utbyta information med API:et. Design och framtagning av specifikationen utgör grunden vid framtagning API:et, utveckling enligt specifikationen och driftsättningen av det som utvecklats, blir en instans av API:et. Ett vanligt scenario för en API-instans är att det finns en endpoint för "mocktjänst-instans", test-instans och produktions-instans.

En API-instans hos Serviceförvaltningen Integration kan vara ett API som utvecklats av intern personal, men det kan även vara ett API i ett extern system eller en kombination av dessa. Utöver att enbart API:et instansieras, så kan "policys" appliceras ovan på API:et. En policy kan exempelvis vara en typ av behörighetsstyrning eller throttling (antal tillåtna anrop per tidsintervall).

Ett API behöver inte ha en instans kopplat till denna portal för att finnas här, utan kunder/system kan exponera sina publika API-specifikationer och sedan hantera API-instansen helt utanför denna plattform.

Publika eller privata API:er?

Publika API:er visas i denna publika portal. Det innebär att ett urval gjorts baserats på flera olika aspekter, om en API-specifikation och -implementation ska vara tillgänglig för alla eller bara en begränsad mängd. Bara för att en specifikation är publik, behöver inte det betyda att implementationen är det. För access till privata API:er samt vissa typer av publika implementationer, krävs ett konto med rätt behörighet i denna portal.

För frågor om användarkonton och access eller annan information om Integrationsförvaltningen och API:er, se Vårdgivarguiden